.TH std::fpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::fpos \- std::fpos

.SH Synopsis
   Defined in header <ios>
   template< class State >
   class fpos;

   Specializations of the class template std::fpos identify absolute positions in a
   stream or in a file. Each object of type fpos holds the byte position in the stream
   (typically as a private member of type std::streamoff) and the current shift state,
   a value of type State (typically std::mbstate_t).

   The following typedef names for std::fpos<std::mbstate_t> are provided (although
   they are spelled differently in the standard, they denote the same type):

   Defined in header <iosfwd>
   Type                      Definition
   std::streampos            std::fpos<std::char_traits<char>::state_type>
   std::wstreampos           std::fpos<std::char_traits<wchar_t>::state_type>
   std::u8streampos(C++20)   std::fpos<std::char_traits<char8_t>::state_type>
   std::u16streampos \fI(C++11)\fP std::fpos<std::char_traits<char16_t>::state_type>
   std::u32streampos \fI(C++11)\fP std::fpos<std::char_traits<char32_t>::state_type>

   All specializations of fpos meet the DefaultConstructible, CopyConstructible,
   CopyAssignable, Destructible, and EqualityComparable requirements.

   If State is trivially copy constructible, fpos has a trivial copy constructor. If
   State is trivially copy assignable, fpos has a trivial copy assignment operator. If
   State is trivially destructible, fpos has a trivial destructor.

.SH Type requirements
   -
   State must meet the requirements of Destructible, CopyAssignable, CopyConstructible
   and DefaultConstructible.

.SH Member functions

   state gets/sets the value of the shift state
         \fI(public member function)\fP

   In addition, member and non-member functions are provided to support the following
   operations:

     * A default constructor that stores an offset of zero and value-initializes the
       state object.
     * A non-explicit constructor that accepts an argument of type (possibly const)
       std::streamoff, which stores that offset and value-initializes the state object.
       This constructor must also accept the special value std::streamoff(-1): the
       std::fpos constructed in this manner is returned by some stream operations to
       indicate errors.
     * Explicit conversion from (possibly const) fpos to std::streamoff. The result is
       the stored offset.
     * operator== and operator!= that compare two objects of type (possibly const)
       std::fpos and returns a value of type convertible to bool. p != q is equivalent
       to !(p == q).
     * operator+ and operator- such that, for an object p of type (possibly const)
       fpos<State> and an object o of type (possibly const) std::streamoff

     * p + o has type fpos<State> and stores an offset that is the result of adding o
       to the offset of p.
     * o + p has a type convertible to fpos<State> and the result of the conversion is
       equal to p + o.
     * p - o has type fpos<State> and stores an offset that is the result of
       subtracting o from the offset of p.
     * operator+= and operator-= which can accept a (possibly const) std::streamoff and
       adds/subtracts it from the stored offset, respectively.
     * operator- which can subtract two objects of type (possibly const) std::fpos
       producing an std::streamoff, such that for two such objects p and q, p == q + (p
       - q).

.SH Notes

   Some of the I/O streams member functions return and manipulate objects of member
   typedef pos_type. For streams, these member typedefs are provided by the template
   parameter Traits, which defaults to std::char_traits, which define their pos_types
   to be specializations of std::fpos. The behavior of the I/O streams library is
   implementation-defined when Traits::pos_type is not std::fpos<std::mbstate_t> (aka
   std::streampos, std::wstreampos, etc.).

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published               Correct behavior
                      streampos and wstreampos were contradictionally  clarified to
   LWG 57  C++98      allowed to be different while required to be the be the same
                      same
   P0759R1 C++98      specification was unclear and incomplete         cleaned up
   P1148R0 C++11      unclear what and in which header the             made clear
                      definitions u16streampos and u32streampos are

.SH See also

             represents relative file/stream position (offset from fpos), sufficient to
   streamoff represent any file size
             \fI(typedef)\fP
   tellp     returns the output position indicator
             \fI(public member function of std::basic_ostream<CharT,Traits>)\fP
   seekp     sets the output position indicator
             \fI(public member function of std::basic_ostream<CharT,Traits>)\fP
   fgetpos   gets the file position indicator
             \fI(function)\fP
